##############
# (*) Kaleidoscope
# By: Allan Spale
# July 2008

import sys

class KSTransactionFactoryError(Exception):
    """
    Exception class for KSTransaction

    """
    B_UNKNOWN_EXCEPTION = True
    B_CLASS_EXCEPTION = False


    def __init__(self, u_message):
        self.__u_message = u_message
    def __str__(self):
        return repr(self.__u_message)

    @staticmethod
    def print_and_raise_error(u_message, b_unknown_exception):
        """
        Convenience method for printing and raising an error for this
        particular Exception subclass.

        """
        u_message = u'KSTransactionFactory.py: ' + u_message
        sys.stderr.write(u_message + u'\n')

        if (b_unknown_exception):
            raise Exception(u_message)
        else:
            raise KSTransactionFactoryError(u_message)


class KSTransactionFactory(object):
    """
    Provide a general transaction factory that is not tied to a particular
    datastore platform. The interface for this object is based on BSDDB.

    """

    def __init__(self, environment):
        """
        Receive the environment used to generate the start of the transaction.

        """
        self.environment = environment


    def create_transaction(self, kstx_parent_transaction, i_flags,
                               fn_caller):
        """
        Generate a new transaction that includes the function that created
        the transaction object.

        """
        raise NotImplementedError, \
            u'begin_transaction must be implemented in a subclass.'